Saar AMOK 2/Saar AMOK II - Oktober 1994 (1994)(Kreativ Marketing)(DE)[!][I-7598].iso/tools/saarcat/fishcat.doc

Text File | 1994-01-06 | 16KB | 362 lines

FishCat V1.2
============

  So, Kickstart 2.0 is here, and boy does it look GREAT!! (thanks guys :-))
But all of your applications still open their own screens in hires,
non-interlace embarassing you in front of your friends.  Once I experienced
2.0 along with its usable Workbench, I wanted EVERYTHING to open a window on
the workbench with 3D buttons (no read/blue glasses required).

  FishCat is intended to be a replacement for Aquarium.  Aquarium is one of
my more "dog-eared" programs, and although it ran beautifully under 2.0, it
was somewhat of an aesthetic shock from my crisp hires, interlace, overscan
workbench.  I also found myself using Aquarium to look for programs, and
writing the items I wanted on a slip of paper.  So I said to myself, "HEY!!
these are the nineties... and you want to learn 2.0 anyway."

  FishCat allows you to search a database consisting of the programs on all
existing Fish disks.  The influence of Aquarium is extremely evident, but I
hope there are enough enhancements to make some people happy.


REQUIREMENTS
------------

    FishCat was designed to be run on a HIRES, INTERLACED, OVERSCAN screen.
Its window is 640x200, so it will fit on a hires, non-interlaced screen, but
things will be a bit out of proportion (I personally feel that running your
Amiga in less than hires, interlaced mode does a disservice to the Amiga and
makes it look like a toy although for memory reasons, I realize it can be
necessary).  You MUST have the HELVETICA font in both 11 and 13 points
available for this thing to look suitably impressive.  While certainly not
required, I would recommend finding a terminal program that opens a public
screen (or at least opens on the workbench).  TERM 1.9c is my personal
choice (but my demands are very reasonable, so it may not meet your needs).
FishCat functions very well on my A3000/16, but I can make no performance
promises on slower machines.  It requires ~290K when running.  I have not
tested FishCat on a floppy, but I assume performance would be pathetic as
in any application of this type.


PERFORMANCE
-----------

    I have spent a reasonable amount of time optimizing many of the searches
in FishCat.  On an Amiga 3000/16, the entire current database can be
searched for an arbitrary string in the description field in approximately
50 seconds compared to 1 minute 30 seconds for Aquarium.  Title and flag
searches take less than 3 seconds.


FEATURES
--------

   - Reasonably fast searches
   - Can open on a specific public screen or the default public screen
   - "Iconifies" (using the 2.0 "zoom" gadget)
   - Database is generally less susceptible to corruption than other efforts
   - Internal support for adding new fish disks.
      - Disks can be added in any order/combination
      - Supports dropping "contents files" on the FishCat window to
        automatically add them to the database (AppWindow)
      - Database corruption is almost always limited to one fish disk
      - Errors in the database can be corrected by simply re-adding the files
*     - Suports custom "upgrade files" for easy upgrades
   - Classy 2.0 look
   - Supports configuration through tooltypes
   - Runs from both CLI and Workbench
   - Tons o' nice thoughtful features to make your life easier
*  - AREXX port

    (* indicates a new feature)

Getting Around in FishCat
=========================

Starting FishCat
----------------
    FishCat can be run from both the CLI and Workbench. If run from the CLI,
it accepts a public screen name as its only parameter.  If this is not
specified, FishCat will open on the default public screen (usually the
workbench screen.  I would suggest setting the stack to at least 20000 or
you may experience problems (this is taken care of automatically when
running from the workbench).

    When run from its icon, FishCat supports the following tool types:

     ICONIFY - If set to YES, FishCat will be iconified immediately after
               being run
     PUBSCREEN - If specified, it is set equal to the name (case sensitive)
                 of the public screen on which to open the FishCat window.
     USERBUTTON - If specified, the value will be used as the name of the
                  "user" button rather than the default name("User").
                  Only the first eight characters are used.
     PORTNAME - If specified, the value of this tool type will be used as the
                name of the AREXX port rather than the default (FISHCAT).

The Controls
------------
    The FishCat window contains several gadgets which are described below:

    - Item list
        This is a scrolling list of the items found so far in the current
        search.  It will consist of all of the items on the current disk in
        the case of a disk search, or all of the items matching the given
        title, description, and flags as selected in the case of a
        string/flag search.  This list is functional during a search.
        Clicking on an item in this list during a search terminates the
        search and displays the item selected.

    - Backward/Forward buttons
        These buttons begin a downward/upward search (ie. a search from the
        current disk to lower/higher disks).  In the case of a disk search,
        this will advance to the next lower/higher disk in the database.

    - Stop
        This button will terminate a search in progress.

    - Goto button (» «)
        This button (situated immediately to the right of the Forward search
        button) changes to disk search mode and sets the current disk to the
        disk on which the current item is located.  This is useful if you
        find a particular item, and you want to see what other items are on
        that same disk.

    - Search type
        These radio buttons select which type of search will be performed by
        Backward/Forward buttons.  Clicking Disk search will immediately take
        you to the disk number typed in the corresponding string gadget
        (if in the database).  Clicking "String/Flag" search will clear the
        item window and prepare for a search using the flags specified at
        the right, and the strings entered in the title and description
        string gadgets.  In order for the title and/or description strings
        to be considered in the search, the corresponding checkboxes must
        be checked.

    - Description box
        This scrolling box contains the description of the currently
        selected item.  Immediately above it is the disk number and name of
        the current item.

    - Match/Show button
        This button has two states, "Match" and "Show".  When in "match mode",
        the selected flags will be used during any subsequent string/flag
        searches.  When in "show mode", the flags set for the currently
        selected item are displayed in the flag gadgets.

    - Set Button
        This button is only available in show mode.  It sets the flags for
        the current item to those selected using the flag gadgets.

    - Next/Previous Item buttons
        These buttons are the plus(+) and minus(-) buttons located immediately
        next to the recessed box containing the disk number and item name.
        The plus/next button will advance to the next item in the item list,
        while the minus/previous button will go back one item.

    -User flag
        The user flag acts like a normal flag in every respect. It can be
        set, cleared, and searched for.  Although by default this flag is
        named "User", it can be renamed using the USERBUTTON tooltype (I
        personally name mine "Download" and use it to mark those files I
        want to download later).  The User flag is different from the other
        flags in only one respect.  There is no need to select the set
        button to set the state of the user flag.  As soon as the user flag
        is clicked, the entry for that item is changed in the database (it
        must still be saved to disk if you want the change to be permanent).
        There is also a menu item that can be used to clear the user flag
        for ALL items in the database.  This flag is intended to be used as
        a volatile flag to mark items for whatever reason you want to mark
        them.


    NOTES:
      - Holding the SHIFT key when clicking on the Backward/Forward
        buttons, will take you to the first/last disk before performing the
        specified function.  This means that shift-clicking while in disk
        search simply takes you to the first or last disk, but while
        performing a string/flag search, the search will merely start from
        the lowest/highest disk.

      - If a search is interrupted, clicking the Backward/Forward button
        will continue the search from the disk where the search was stopped
        (clearing the item list first).

      - Typing in the disk number gadget and pressing enter will
        auomatically switch to disk search mode and goto the selected disk.
        Typing in the title or description string gadgets and pressing enter
        will automatically switch to string/flag search mode and check the
        entered field.

      - If the window is iconified during a search, the disk being
        searched is displayed in the ttle bar of the FishCat window.

      - The small buttons to the left of the title and description
        string gagdets can be used to copy the name of the current item to
        the corresponding string gadget.

      - The UP/DOWN arrow keys perform the same functions as the
        backward/forward buttons.  The LEFT/RIGHT arrows keys perform the
        same functions as the Next/Prev item buttons.  Qualifier keys modify
        the actions of these keys in exactly the same way the actual buttons
        are modified.


Adding New Disks
----------------

    Adding new fish disks to FishCat is mind bogglingly simple.  You can...

A) Drop one or more "Contents.###" files on the FishCat window
   (this will automatically add them to the database)

B) Select "Read New Disks..." from the Project menu.  This will bring up the
   ASL file requester to select a file.  The selected "Contents.###" file
   will be added to the database.  If you do not select a file, but click
   "Okay" in the file requester with only a directory selected, The entire
   directory will be read and all contents files will be added to the
   database.

    If FishCat reports that a file is corrupt, this merely means that it
could not decipher the format of the file.  Many early fish disks (<100)
were poorly formatted at best, and will not be added to the database
correctly.  If this happens, merely edit the contents file and try again.
The file must have the text "This is disk ###" as its first non-blank line,
and each item should consist of the item name followed immediately by
a description (possibly indented).  I had NO problems with ANY disk after
200 (and only a couple between 100 and 200).  Also, my algorithm is much
more robust than I described above, but the above format is your best bet.


Update Files
------------

    Version 1.2 of FishCat now supports a custom update file format.  These
update files contain all of the information neccessary for adding a disk to
the library (item titles, descriptions, and flags).  Update files are added
to the database in exactly the same ways as contents files ("drag and drop"
or the "Read New Disks..." menu).  Update files can be added in any order,
and re-adding an update file will only negate any changes to the flags for
those items that the user may have made.
    In order to create update files, the FCExport utility is provided.
FCExport can only be run from the CLI, and expects three parameters.  Typing
FCExport with no parameters will display the following usage:

    FCExport OutputFile StartDisk EndDisk

    This will create the file "OutputFile" containing all of the information
about disks "StartDisk" through "EndDisk" necessary to update another FishCat
database.  A normal user should not need to use FCExport.


The Database
------------

    I have opted not to support the aquarium database format.  This is
largely due to the fact that I had corrupted my database one too many times
trying to add new disks.
    My database consists of an INDEX containing the name, flags, and offset
for each entry in the library.  There is also a "data" directory containing
one directory for every 100 Fish disks.  Each disk directory contains upto
100 "Contents" files.  These contents files are stripped down versions of
the ACTUAL contents files located on the original disks.  I realize it may
seem absurd to store each disk in its own file rather than one HUGE one, but
I have experienced no problems, it dramatically reduces the chance of
corrupting the database, and it allows for faster operation in many cases.
    The only file you really need to backup when adding new disks might be
your index file, as it is theoretically possible to trick the program into
reading an invalid file.  Again, this could only corrupt the index and even
this is not likely.  To facilitate this, there is a "Save as..." menu item
for backing up the index.


AREXX Commands
--------------

    Starting with version 1.2, FishCat supports AREXX.  Currently only three
commands are recognized.  The default AREXX port is named FISHCAT, but this
can be changed through the PORTNAME tooltype.

    QUIT [FORCE] - Exits the FishCat application (the FORCE option supresses
                    the "Save" requester if necessary)
    GETDISK - Returns the disk number of the currently selected item (value
                is in the "RESULT" variable)
    GETITEM - Returns the name of the currently selected item (value is
                returned in the "RESULT" variable)

    I have included some simple AREXX scripts to show how I meant for this
all to work.  They are very specific to the particular mainframe to which
I have access, but they should serve as suitable examples.


Changes from v1.1 to v1.2
-------------------------

(B=Bug fix, E=Enhancement)

B -Corrected cosmetic problems regarding non-Topaz8 system fonts.

B -Removed memory leak and cleaned up exit code (hopefully :-)).

B -Removed silly bug regarding adding contents files from root of volume.

E -Added AREXX port (named FISHCAT).

E -Added buttons to allow displaying previous/next item without using the
    item list.

E -Added cursor keys as equivalents for arrow and prev/next item buttons.

E -Added support for flexible update files (including FCExport).


Special Thanks
--------------

    I would be remiss if I did not thank the following people:

        - Fred Fish for providing an AMAZING and UNPARALLELED service to the
          Amiga community
        - B Lennart Olson for Aquarium which I used to find most of the
          utilities and programs on my system.
        - Matt Dillon for DICE.  An amazing compiler(try it, you'll
          like it :-))
        - EVERYONE WHO SENT ME $10 AND MOTIVATED THIS AND OTHER PROJECTS.
        - John Novak for beta testing, and many helpful suggestions
        - My girlfriend for allowing me to ignore her long enough to write
          this program
        - And FAR FROM LEAST, the Commodore team who gave us and continues
          to improve this incredible machine (WOW!!)



THIS PROGRAM IS SHAREWARE!!!
============================

    If you use this program, clear your conscience and motivate further
development by sending $10 to the following address:

    Matt Brown
    2403 W. Springfield Ave. Apt.Y-8
    Champaign, IL 61821


    If 10 bucks is out of your league, at least let me know you're using it,
and send me your comments.

    E-Mail sent to [e-mail] will also be forwarded to me.



    Most of all, enjoy this program!!

    If something is missing that is necessary for this program to be useful
to you, LET ME KNOW!  I can't change it if I don't know about it.


    Oh yah... ofcourse, I am not responsible for any damage this program
might cause.  It has done me no harm in ANY of its incarnations, so I would
classify it as "Mostly Harmless" :-)